#!/usr/bin/env python3
"""
daksign.py - control a Daktronics Galaxy AE-3010-16x128 (MDC controller) LED
message display from Linux over RS-232 / RS-422 (serial or USB adapter) or TCP.

Sign control (Venus 1500 protocol):
  v15status      display type, clock, running message, brightness
  v15settime     set the sign's clock from this computer
  v15list        message and graphic files on the sign
  v15message     build, upload and run a message: text frames (effects, speed,
                 colours, fonts, live time/date), graphic frames and
                 full-height scrolling banners
  v15upload      upload message / graphic files as they are
  v15run / v15stop / v15off   run a message, stop it, display off
  v15brightness  min / medium / max / auto / 0-63
  v15reset       restart the controller and wait until it answers again
  v15diag        diagnostics on / off
Tools:
  simulate       a simulated sign on TCP, for testing without hardware
  hexsend        send raw bytes and show the reply
RTD commands (Daktronics Real-Time Data, for controllers with an RTD input):
  text, clock, settime, raw, checksum

Requires Python 3.8+ and pyserial; Pillow for graphic and banner frames.
See "Daktronics AE-3010 Protocol and daksign.py User Guide".
"""

from __future__ import annotations

import argparse
import datetime as _dt
import re
import select
import socket
import sys
import threading
import time
from dataclasses import dataclass
from typing import Iterator, List, Optional, Tuple

try:
    import serial  # pyserial
except ImportError:  # allow --help, checksum and simulate without pyserial
    serial = None

# --------------------------------------------------------------------------
# Protocol constants
# --------------------------------------------------------------------------
SYN, SOH, STX, EOT, ETB = 0x16, 0x01, 0x02, 0x04, 0x17
DEFAULT_HEADER = "20000000"
RTD_TEXT_TABLE = "4010"          # control "00" + "4010" + "NNNN" = positioned text
DEFAULT_BAUD = 19200             # Galaxy default (Daktronics ED-17910)

ACK_CODES = {
    "0000": "OK - frame accepted",
    "0003": "checksum error",
    "0099": "unrecognised / garbage frame",
}


def checksum(body: bytes) -> str:
    """Sum of bytes from the first HEADER byte through EOT inclusive, mod 256,
    rendered as two upper-case ASCII hex digits."""
    return "%02X" % (sum(body) & 0xFF)


@dataclass
class Frame:
    header: str
    control: str
    data: bytes = b""
    has_data: bool = True          # ACK frames have no <STX> section
    cksum_ok: Optional[bool] = None

    # ---- encoding -------------------------------------------------------
    def body(self) -> bytes:
        b = self.header.encode("ascii") + bytes([SOH]) + self.control.encode("ascii")
        if self.has_data:
            b += bytes([STX]) + self.data
        return b + bytes([EOT])

    def encode(self) -> bytes:
        body = self.body()
        return bytes([SYN]) + body + checksum(body).encode("ascii") + bytes([ETB])

    # ---- presentation ---------------------------------------------------
    def describe(self) -> str:
        s = f"header={self.header!r} control={self.control!r}"
        if self.has_data:
            s += f" data={printable(self.data)!r}"
        if self.cksum_ok is not None:
            s += "" if self.cksum_ok else "  [BAD CHECKSUM]"
        if self.control.startswith("9") and len(self.control) == 5:
            s += f"  -> ACK: {ACK_CODES.get(self.control[1:], 'unknown status ' + self.control[1:])}"
        elif len(self.control) == 10 and self.control.isdigit():
            s += f"  (table {self.control[2:6]}, offset {int(self.control[6:])})"
        return s

    @property
    def is_ack_ok(self) -> bool:
        return self.control == "90000"


def printable(b: bytes) -> str:
    return "".join(chr(c) if 32 <= c < 127 else f"\\x{c:02x}" for c in b)


def parse_frame(raw: bytes) -> Frame:
    """raw = bytes between SYN and ETB (exclusive)."""
    soh = raw.find(bytes([SOH]))
    eot = raw.rfind(bytes([EOT]))
    if soh < 0 or eot < 0 or eot < soh:
        raise ValueError("not a Daktronics frame: " + printable(raw))
    header = raw[:soh].decode("ascii", "replace")
    middle = raw[soh + 1:eot]
    stx = middle.find(bytes([STX]))
    if stx >= 0:
        control, data, has_data = middle[:stx].decode("ascii", "replace"), middle[stx + 1:], True
    else:
        control, data, has_data = middle.decode("ascii", "replace"), b"", False
    got = raw[eot + 1:].decode("ascii", "replace").strip()
    ok = got.upper() == checksum(raw[:eot + 1])
    return Frame(header, control, data, has_data, ok)


class FrameReader:
    """Incremental SYN...ETB frame extractor for a byte stream."""

    def __init__(self) -> None:
        self.buf = bytearray()
        self.in_frame = False

    def feed(self, data: bytes) -> Iterator[Tuple[str, object]]:
        """Yields ("frame", Frame) or ("junk", bytes)."""
        for c in data:
            if c == SYN:
                if self.buf and not self.in_frame:
                    yield "junk", bytes(self.buf)
                self.buf.clear()
                self.in_frame = True
            elif c == ETB and self.in_frame:
                raw = bytes(self.buf)
                self.buf.clear()
                self.in_frame = False
                try:
                    yield "frame", parse_frame(raw)
                except ValueError:
                    yield "junk", raw
            else:
                self.buf.append(c)


# --------------------------------------------------------------------------
# Transports
# --------------------------------------------------------------------------
class Transport:
    def write(self, data: bytes) -> None: ...
    def read(self, timeout: float) -> bytes: ...
    def close(self) -> None: ...
    def fileno(self) -> int: ...


class SerialTransport(Transport):
    def __init__(self, port: str, baud: int = DEFAULT_BAUD, parity: str = "N",
                 bytesize: int = 8, stopbits: int = 1, rtscts: bool = False,
                 rts: Optional[bool] = None, dtr: Optional[bool] = None):
        if serial is None:
            sys.exit("pyserial is required for serial ports:  pip install pyserial")
        self.s = serial.Serial(port, baudrate=baud, parity=parity, bytesize=bytesize,
                               stopbits=stopbits, rtscts=rtscts, timeout=0)
        if rts is not None:
            self.s.rts = rts
        if dtr is not None:
            self.s.dtr = dtr

    def write(self, data: bytes) -> None:
        self.s.write(data)
        self.s.flush()

    def read(self, timeout: float) -> bytes:
        r, _, _ = select.select([self.s.fileno()], [], [], timeout)
        return self.s.read(self.s.in_waiting or 1) if r else b""

    def fileno(self) -> int:
        return self.s.fileno()

    def close(self) -> None:
        self.s.close()


class TcpTransport(Transport):
    def __init__(self, host: str, port: int, timeout: float = 5.0):
        self.sock = socket.create_connection((host, port), timeout=timeout)
        self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)

    def write(self, data: bytes) -> None:
        self.sock.sendall(data)

    def read(self, timeout: float) -> bytes:
        r, _, _ = select.select([self.sock], [], [], timeout)
        if not r:
            return b""
        d = self.sock.recv(4096)
        if not d:
            raise ConnectionError("connection closed by remote end")
        return d

    def fileno(self) -> int:
        return self.sock.fileno()

    def close(self) -> None:
        self.sock.close()


class UdpTransport(Transport):
    def __init__(self, host: str, port: int):
        self.addr = (host, port)
        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)

    def write(self, data: bytes) -> None:
        self.sock.sendto(data, self.addr)

    def read(self, timeout: float) -> bytes:
        r, _, _ = select.select([self.sock], [], [], timeout)
        return self.sock.recvfrom(4096)[0] if r else b""

    def fileno(self) -> int:
        return self.sock.fileno()

    def close(self) -> None:
        self.sock.close()


def hostport(s: str, default_port: int) -> Tuple[str, int]:
    if ":" in s:
        h, p = s.rsplit(":", 1)
        return h, int(p)
    return s, default_port


def open_transport(a: argparse.Namespace) -> Transport:
    if getattr(a, "tcp", None):
        return TcpTransport(*hostport(a.tcp, 3001))
    if getattr(a, "udp", None):
        return UdpTransport(*hostport(a.udp, 3002))
    if getattr(a, "serial", None):
        return SerialTransport(a.serial, a.baud, a.parity, a.bytesize, a.stopbits,
                               a.rtscts, rts=a.rts, dtr=a.dtr)
    sys.exit("choose a link: --serial /dev/ttyUSB0 | --tcp HOST[:PORT] | --udp HOST[:PORT]")


# --------------------------------------------------------------------------
# Sign API
# --------------------------------------------------------------------------
class DakSign:
    def __init__(self, link: Transport, header: str = DEFAULT_HEADER,
                 ack_timeout: float = 1.0, retries: int = 2, verbose: bool = False):
        self.link = link
        self.header = header
        self.ack_timeout = ack_timeout
        self.retries = retries
        self.verbose = verbose
        self.reader = FrameReader()

    def _log(self, msg: str) -> None:
        if self.verbose:
            print(msg, file=sys.stderr)

    def send_frame(self, frame: Frame, wait_ack: bool = True) -> Optional[Frame]:
        pkt = frame.encode()
        for attempt in range(self.retries + 1):
            self._log(f"TX {printable(pkt)}")
            self.link.write(pkt)
            if not wait_ack:
                return None
            reply = self.wait_frame(self.ack_timeout)
            if reply is None:
                self._log(f"  no reply (attempt {attempt + 1})")
                continue
            self._log(f"RX {reply.describe()}")
            if reply.is_ack_ok or not reply.control.startswith("9"):
                return reply
            if reply.control == "90003":      # checksum error -> retry
                continue
            return reply
        return None

    def wait_frame(self, timeout: float) -> Optional[Frame]:
        end = time.monotonic() + timeout
        while True:
            left = end - time.monotonic()
            if left <= 0:
                return None
            chunk = self.link.read(min(left, 0.1))
            for kind, item in self.reader.feed(chunk):
                if kind == "frame":
                    return item  # type: ignore[return-value]
                self._log(f"  junk: {printable(item)}")  # type: ignore[arg-type]

    # ---- RTD positioned text -------------------------------------------
    def rtd_text(self, offset: int, text: str, length: Optional[int] = None,
                 table: str = RTD_TEXT_TABLE, chunk: int = 0,
                 wait_ack: bool = True, encoding: str = "latin-1") -> List[Optional[Frame]]:
        """Write text into the sign's RTD buffer at a 0-based offset.
        If length is given the text is truncated / space-padded so that old
        characters in the field are overwritten."""
        if length is not None:
            text = text[:length].ljust(length)
        data = text.encode(encoding, "replace")
        pieces = [(offset, data)] if chunk <= 0 else [
            (offset + i, data[i:i + chunk]) for i in range(0, len(data), chunk)]
        replies = []
        for off, piece in pieces:
            if not 0 <= off <= 9999:
                raise ValueError("offset must be 0..9999")
            control = "00" + table + "%04d" % off
            replies.append(self.send_frame(Frame(self.header, control, piece), wait_ack))
        return replies


# --------------------------------------------------------------------------
# Escapes: "\x16" style strings on the command line / in templates
# --------------------------------------------------------------------------
def unescape(s: str) -> bytes:
    return s.encode("latin-1", "backslashreplace").decode("unicode_escape").encode("latin-1")


# --------------------------------------------------------------------------
# Commands
# --------------------------------------------------------------------------
def _sign(a) -> DakSign:
    return DakSign(open_transport(a), a.header, a.ack_timeout, a.retries, a.verbose)


def _report(replies) -> int:
    rc = 0
    for r in replies:
        if r is None:
            print("no acknowledgement" if not NO_ACK else "sent (not waiting for ACK)")
            rc = 0 if NO_ACK else 1
        else:
            print("reply:", r.describe())
            rc = rc or (0 if r.is_ack_ok else 2)
    return rc


NO_ACK = False


def offset_from(a) -> int:
    if a.item is not None:
        return a.item - 1           # Venus "Item Number" is 1-based
    return a.offset


def cmd_text(a) -> int:
    sign = _sign(a)
    try:
        return _report(sign.rtd_text(offset_from(a), a.text, a.length, a.table,
                                     a.chunk, not a.no_ack))
    finally:
        sign.link.close()


def cmd_clock(a) -> int:
    """Keep RTD time (and optional date) fields in step with the Linux clock."""
    sign = _sign(a)
    last = None
    try:
        while True:
            now = _dt.datetime.now()
            t = now.strftime(a.time_format)
            if a.strip_leading_zero and t.startswith("0"):
                t = " " + t[1:]
            if t != last or a.force:
                sign.rtd_text(a.time_offset, t, a.time_length or len(t), a.table,
                              wait_ack=not a.no_ack)
                if a.date_offset is not None:
                    d = now.strftime(a.date_format)
                    sign.rtd_text(a.date_offset, d, a.date_length or len(d), a.table,
                                  wait_ack=not a.no_ack)
                print(now.isoformat(timespec="seconds"), "->", repr(t), flush=True)
                last = t
            if a.once:
                return 0
            # sleep to the next whole second
            time.sleep(max(0.05, 1.0 - (time.time() % 1.0)))
    except KeyboardInterrupt:
        return 0
    finally:
        sign.link.close()


def cmd_settime(a) -> int:
    """RTD: send a set-time frame built from a control field and a template;
    data-format is a
    strftime() string that may also contain \\xNN escapes for binary bytes."""
    if a.at:
        when = _dt.datetime.fromisoformat(a.at)
    elif a.utc:
        when = _dt.datetime.now(_dt.timezone.utc)
    else:
        when = _dt.datetime.now()
    data = unescape(when.strftime(a.data_format))
    frame = Frame(a.header, a.control, data, has_data=not a.no_stx)
    print("frame:", printable(frame.encode()))
    if a.dry_run:
        return 0
    sign = _sign(a)
    try:
        return _report([sign.send_frame(frame, not a.no_ack)])
    finally:
        sign.link.close()


def cmd_raw(a) -> int:
    frame = Frame(a.header, a.control, unescape(a.data), has_data=not a.no_stx)
    print("frame:", printable(frame.encode()))
    if a.dry_run:
        return 0
    sign = _sign(a)
    try:
        return _report([sign.send_frame(frame, not a.no_ack)])
    finally:
        sign.link.close()


def cmd_hexsend(a) -> int:
    data = bytes.fromhex(" ".join(a.hex))
    link = open_transport(a)
    try:
        link.write(data)
        end = time.monotonic() + a.wait
        got = b""
        while time.monotonic() < end:
            got += link.read(0.1)
        print("sent:", data.hex(" "))
        print("recv:", got.hex(" ") if got else "(nothing)")
        if got:
            print("      ", printable(got))
        return 0
    finally:
        link.close()












# ---- simulate: fake sign for testing --------------------------------------
def cmd_simulate(a) -> int:
    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    srv.bind(("127.0.0.1" if a.localhost else "0.0.0.0", a.port))
    srv.listen(5)
    print(f"simulated sign listening on TCP {a.port} ({a.width}x{a.height}); Ctrl-C to stop",
          flush=True)
    buffer = bytearray(b" " * 2048)

    def ack(code: str) -> bytes:
        return Frame(DEFAULT_HEADER, "9" + code, has_data=False).encode()

    v15 = {"clock": _dt.datetime.now(), "running": b"", "files": {}, "gfx": False, "open": None,
           "auto": 1, "level": 0x3F, "down_until": 0.0}

    def v15_reply(p: bytes) -> bytes:
        """Simulated MDC controller: answers like the sign does."""
        n, ctrl = p[3], p[4]
        if n == 0:
            return v15_packet(V15_CONNECT, b"\x00\xff")
        d = p[6:6 + n]
        op = d[0]
        body = bytearray([op, 0]) + bytearray(6)
        if op == OP_SETTIME:
            sec, mn, hr, day, mon, yr = d[2:8]
            v15["clock"] = _dt.datetime(1900 + yr, mon + 1, day, hr, mn, sec)
        elif op == OP_STATUS:
            st = bytearray(128)
            st[0] = op
            st[1:18] = b"Galaxy 16x128 Tri"
            st[27:33] = v15_ts_bytes(v15["clock"])
            st[33:39] = v15_ts_bytes(v15["clock"])
            st[41] = v15["auto"]
            st[42] = v15["level"]
            st[43] = 1 if v15["running"] else 0
            st[44:44 + len(v15["running"])] = v15["running"]
            st[62:73] = b"No Schedule"
            body = st
        elif op in (OP_SELECT_MSG, OP_SELECT_GFX):
            v15["gfx"] = op == OP_SELECT_GFX
            body = bytearray([op, 1, 0, 1, 0, 0xE0, 0, 0, 1 if v15["running"] else 0]) + bytearray(7)
        elif op == OP_LIST:
            body = bytearray(232)
            body[0] = op
            k = 0
            for nm, (g, ts, data) in v15["files"].items():
                if g == v15["gfx"] and k < 8:
                    e = 8 + 28 * k
                    body[e:e + 17] = v15_name(nm)
                    body[e + 17:e + 23] = ts
                    body[e + 23:e + 27] = len(data).to_bytes(4, "little")
                    k += 1
        elif op in (OP_CREATE_MSG, OP_CREATE_GFX):
            nm = bytes(d[2:19]).split(b"\0")[0].decode()
            size = int.from_bytes(d[29:33], "little")
            v15["open"] = (nm, op == OP_CREATE_GFX, bytes(d[19:25]), size, bytearray())
        elif op == OP_DATA and v15["open"]:
            nm, g, ts, size, buf = v15["open"]
            buf += d[8:255]
            if len(buf) >= size:
                v15["files"][nm] = (g, ts, bytes(buf[:size]))
                print(f"SIGN(v15) stored {'graphic' if g else 'message'} {nm!r} ({size} bytes)",
                      flush=True)
                if not g:
                    print("          script:", printable(bytes(buf[:size])), flush=True)
                else:
                    px = gfx_decode(bytes(buf[:size]))
                    for y in range(GFX_H):
                        print("          " + "".join("#" if px(x, y) else "." for x in range(GFX_W)))
        elif op == OP_RUN:
            v15["running"] = bytes(d[2:19]).split(b"\0")[0]
        elif op in (OP_STOP_MSG, OP_OFF):
            v15["running"] = b""
        elif op == OP_BRIGHT:
            v15["auto"], v15["level"] = d[1], d[2]
        elif op == OP_RESET:
            v15["running"] = b""
            v15["down_until"] = time.monotonic() + a.reset_time
            if d[2]:
                v15["files"].clear()
        return v15_packet(ctrl | 1, bytes(body))

    def handle_v15(conn: socket.socket, buf: bytearray) -> None:
        while True:
            while len(buf) >= 6:
                n = buf[3]
                total = 6 + (n + 1 if n else 0)
                if len(buf) < total:
                    break
                p, buf[:] = bytes(buf[:total]), buf[total:]
                if time.monotonic() < v15["down_until"]:
                    print("SIGN(v15) restarting - packet ignored", flush=True)
                    continue
                ok = sum(p[:6]) & 0xFF == 0 and (n == 0 or sum(p[6:]) & 0xFF == 0)
                desc = v15_describe({"dir": "pc>sign", "len": total, "data": list(p)})
                print("SIGN(v15) got:", desc, "" if ok else "[BAD CHECKSUM]", flush=True)
                if ok:
                    conn.sendall(v15_reply(p))
            d = conn.recv(4096)
            if not d:
                return
            buf += d

    def handle(conn: socket.socket) -> None:
        rd = FrameReader()
        with conn:
            while True:
                d = conn.recv(4096)
                if not d:
                    return
                if d[0] == V15_SYNC:
                    return handle_v15(conn, bytearray(d))
                for kind, item in rd.feed(d):
                    if kind != "frame":
                        conn.sendall(ack("0099"))
                        continue
                    fr: Frame = item  # type: ignore[assignment]
                    if not fr.cksum_ok:
                        conn.sendall(ack("0003"))
                        continue
                    if len(fr.control) == 10 and fr.control[2:6] == RTD_TEXT_TABLE:
                        off = int(fr.control[6:])
                        buffer[off:off + len(fr.data)] = fr.data
                    print("SIGN got:", fr.describe(), flush=True)
                    print("   RTD buffer[0:80] =", repr(buffer[:80].decode("latin-1")), flush=True)
                    conn.sendall(ack("0000"))

    try:
        while True:
            c, _ = srv.accept()
            threading.Thread(target=handle, args=(c,), daemon=True).start()
    except KeyboardInterrupt:
        return 0


def cmd_checksum(a) -> int:
    body = unescape(a.body)
    print(checksum(body))
    return 0


# ==========================================================================
# Venus 1500 native (MDC controller) protocol
# ==========================================================================
#
#   55 AA 01  N  CTRL  HCS  | DATA (N bytes) | DCS
#
#   55 AA 01  fixed start (same in both directions)
#   N         number of DATA bytes (DCS not counted); N=0 -> no DATA, no DCS
#   CTRL      0x03 = connect (first packet of every session, echoed by sign)
#             otherwise high nibble = sequence 1..15 (wraps to 1),
#             low nibble 0 = PC request, 1 = sign reply
#   HCS       (-(sum of the 5 bytes before it)) & 0xFF   -> header sums to 0
#   DATA[0]   command code (echoed in DATA[0] of the reply); DATA[1] = 00
#   DCS       (-(sum of DATA)) & 0xFF                    -> data sums to 0
#
# Timestamp (6 bytes): sec, min, hour, day, month (0 = January), year-1900.

V15_SYNC = 0x55
V15_HDR = bytes([0x55, 0xAA, 0x01])
V15_CONNECT = 0x03
V15_BLOCK = 247                     # payload bytes per file data block
V15_NAME = 17                       # file-name field width

OP_STATUS, OP_DATA, OP_LIST, OP_CREATE_MSG, OP_RUN, OP_STOP_MSG = 0x02, 0x03, 0x04, 0x05, 0x06, 0x07
OP_SELECT_MSG, OP_OFF, OP_SETTIME, OP_DIAG = 0x09, 0x0F, 0x10, 0x11
OP_CREATE_GFX, OP_SELECT_GFX, OP_RESET, OP_BRIGHT = 0x1A, 0x1B, 0x12, 0x0E
OP_NAMES = {
    OP_STATUS: "GET STATUS", OP_DATA: "FILE DATA BLOCK", OP_LIST: "LIST FILES",
    OP_CREATE_MSG: "CREATE MESSAGE FILE", OP_RUN: "RUN MESSAGE", OP_STOP_MSG: "STOP MESSAGE",
    OP_SELECT_MSG: "SELECT MESSAGE DIRECTORY", OP_OFF: "DISPLAY OFF (stop all)",
    OP_SETTIME: "SET TIME/DATE", OP_DIAG: "DIAGNOSTICS ON/OFF",
    OP_CREATE_GFX: "CREATE GRAPHIC FILE", OP_SELECT_GFX: "SELECT GRAPHIC DIRECTORY",
    OP_RESET: "RESET", OP_BRIGHT: "SET BRIGHTNESS",
}


def v15_packet(ctrl: int, data: bytes = b"") -> bytes:
    if len(data) > 255:
        raise ValueError("DATA is limited to 255 bytes")
    h = V15_HDR + bytes([len(data), ctrl])
    h += bytes([(-sum(h)) & 0xFF])
    return h + data + bytes([(-sum(data)) & 0xFF]) if data else h


def v15_ts(b) -> str:
    """Decode sec,min,hour,day,month0,year-1900 (None = unknown byte)."""
    b = (list(b) + [None] * 6)[:6]
    if None in b:
        f = lambda x: "??" if x is None else "%02d" % x
        return f"{'????' if b[5] is None else 1900 + b[5]}-{f(None if b[4] is None else b[4] + 1)}-" \
               f"{f(b[3])} {f(b[2])}:{f(b[1])}:{f(b[0])}"
    sec, mn, hr, day, mon, yr = b
    return f"{1900 + yr:04d}-{mon + 1:02d}-{day:02d} {hr:02d}:{mn:02d}:{sec:02d}"


def v15_ts_bytes(t: _dt.datetime) -> bytes:
    return bytes([t.second, t.minute, t.hour, t.day, t.month - 1, t.year - 1900])


def v15_name(name: str) -> bytes:
    b = name.encode("ascii")
    if len(b) > V15_NAME:
        raise ValueError(f"file name {name!r} is longer than {V15_NAME} characters")
    return b.ljust(V15_NAME, b"\0")


# ---- message script --------------------------------------------------------
# Example script (197 bytes, 3 frames):
#   0C "020" "G20" "V1500F39_B1F022VV" 00                    graphic, scrolling
#   0C "150" 02 "0101" ESC h008 ESC S50 ESC JC ESC CE0 ESC TE 03   line 1: time
#            02 "0201" ESC h008 ESC S50 ESC JC ESC CE0 ESC DB 03   line 2: date
#   0C "020" 02 "0101" ...attrs... "NerdWorld" 03
#            02 "0201" ...attrs... "This is a long message ..." 03
#   03                                                       end of message
# 0C starts a frame; the 3 digits after it are the hold time in tenths of a
# second ("150" = 15 s); "G00" = static graphic, "G20" = scrolling graphic;
# 02 "LL01" ... 03 is text line LL; ESC TE = time HH:MM:SS AM, ESC DB = date
# "Month day, year"; other text is shown literally in the sign's font.
ESC = b"\x1b"


def _hold(hold) -> bytes:
    h = int(round(float(hold) * 10)) if isinstance(hold, float) else int(hold)
    if not 0 <= h <= 999:
        raise ValueError("hold must be 0.0 .. 99.9 seconds")
    return b"%03d" % h


def gfx_file_name(prefix: str, index: int, data: bytes) -> str:
    """17-character graphic name, like Venus' 'V1500F39_B1F022VV'.  The sign
    reads the name in a graphic frame as a FIXED 17-character field: a shorter
    name makes it read into the next frame, which is then skipped."""
    import hashlib
    h = hashlib.md5(data).hexdigest().upper()
    base = "".join(c for c in prefix.upper() if c.isalnum())[:6] or "LNX"
    return (f"{base}{index:02d}_" + h)[:V15_NAME]


# ---- effects and attributes -------------------------------------------------
# Text line header is 02 "LLEE": LL = line number, EE = entry effect.
TEXT_EFFECTS = {"none": 1, "appear": 1, "scroll-left": 2, "scroll-right": 3,
                "roll-up": 6, "roll-down": 7, "roll-right": 8, "roll-left": 9,
                "travel": 10}
# Graphic frame is "G" + 2-digit entry effect.
GFX_EFFECTS = {"none": 0, "appear": 0, "scroll-left": 20, "scroll": 20,
               "scroll-right": 21, "scroll-up": 22, "scroll-down": 23, "roll-up": 24,
               "wipe-left": 28, "wipe-right": 29}
SPEEDS = {"super-slow": 52, "slow": 51, "normal": 50, "fast": 49, "super-fast": 48}
COLOURS = {"red": "E0", "green": "1C", "amber": "FC"}      # 8-bit RRRGGGBB values
JUSTIFY = {"left": "L", "center": "C", "centre": "C", "right": "R"}
FONTS = {"normal": None, "wide": "1", "fixed": "2", "graphic": "3"}   # ESC N<x>
TIME_FORMATS = {"A": "24:00:00", "B": "24:00", "C": "12:00:00", "D": "12:00",
                "E": "12:00:00 AM", "F": "12:00 AM"}
DATE_FORMATS = {"A": "09/29/00", "B": "September 29, 2000", "C": "Sep 29, 2000"}


def parse_opts(spec: str, base: Optional[dict] = None) -> dict:
    """'roll-up,green,fast,right,font=graphic,e05,speed=50,colour=E0' -> dict."""
    o = dict(base or {})
    for tok in filter(None, (t.strip().lower() for t in spec.split(","))):
        key, _, val = tok.partition("=")
        if val:
            o[{"color": "colour", "effect": "effect", "e": "effect"}.get(key, key)] = val
        elif tok in FONTS:
            o["font"] = tok
        elif tok in TEXT_EFFECTS or tok in GFX_EFFECTS:
            o["effect"] = tok
        elif tok in SPEEDS:
            o["speed"] = tok
        elif tok in COLOURS:
            o["colour"] = tok
        elif tok in JUSTIFY:
            o["justify"] = tok
        elif tok[0] in "eg" and tok[1:].isdigit():
            o["effect"] = int(tok[1:])
        else:
            raise ValueError(f"unknown option {tok!r}")
    return o


def _effect_code(val, table) -> int:
    if isinstance(val, int):
        return val
    if str(val).isdigit():
        return int(val)
    if val not in table:
        raise ValueError(f"effect {val!r} not available here; choose from {', '.join(table)}")
    return table[val]


def _colour_code(val) -> bytes:
    v = COLOURS.get(str(val).lower(), str(val).upper())
    if len(v) != 2:
        raise ValueError(f"colour must be red, green, amber or two hex digits: {val!r}")
    return v.encode()


def _speed_code(val) -> bytes:
    return str(SPEEDS.get(str(val).lower(), val)).encode()


def script_graphic_frame(gfx_name: str, hold="020", scroll: bool = False, effect=None) -> bytes:
    if len(gfx_name) != V15_NAME:
        raise ValueError(f"graphic name must be exactly {V15_NAME} characters "
                         f"(the sign reads a fixed-width field): {gfx_name!r}")
    code = _effect_code(effect, GFX_EFFECTS) if effect is not None else (20 if scroll else 0)
    return (b"\x0c" + _hold(hold) + b"G%02d" % code + gfx_name.encode("ascii") + b"\0")


def script_text_frame(lines: List[str], hold="020", height: str = "008",
                      speed="50", justify: str = "C", colour="E0",
                      effect=1, font=None) -> bytes:
    """One text frame.  Each line may start with [options] overriding the frame
    settings (effect, speed, justify, colour, font).  Inline tokens:
      {time} {time:A..F}  {date} {date:A..C}   live time / date
      {red} {green} {amber} {colour:XX}        change colour mid-line
      {esc:XX}                                  any raw ESC code"""
    import re
    base = {"effect": effect, "speed": speed, "justify": justify, "colour": colour, "font": font}
    out = b"\x0c" + _hold(hold)
    for i, line in enumerate(lines, 1):
        o = dict(base)
        m = re.match(r"\[([^\]]*)\]", line)
        if m:
            o = parse_opts(m.group(1), o)
            line = line[m.end():]
        body = b""
        for tok in re.split(r"(\{[^}]+\})", line):
            t = tok[1:-1].lower() if tok.startswith("{") and tok.endswith("}") else None
            if t is None:
                body += tok.encode("latin-1")
            elif t == "time" or t.startswith("time:"):
                body += ESC + b"T" + (t[5:].upper() or "E").encode()
            elif t == "date" or t.startswith("date:"):
                body += ESC + b"D" + (t[5:].upper() or "B").encode()
            elif t in COLOURS or t.startswith(("colour:", "color:")):
                body += ESC + b"C" + _colour_code(t.split(":", 1)[-1])
            elif t.startswith("esc:"):
                body += ESC + tok[5:-1].encode("latin-1")
            else:
                body += tok.encode("latin-1")
        fnt = FONTS.get(str(o["font"]).lower(), o["font"]) if o["font"] else None
        out += (b"\x02" + b"%02d%02d" % (i, _effect_code(o["effect"], TEXT_EFFECTS))
                + ESC + b"h" + height.encode() + ESC + b"S" + _speed_code(o["speed"])
                + ESC + b"J" + JUSTIFY.get(str(o["justify"]).lower(), str(o["justify"])).encode()
                + (ESC + b"N" + str(fnt).encode() if fnt else b"")
                + ESC + b"C" + _colour_code(o["colour"]) + body + b"\x03")
    return out


def script_message(frames: List[bytes]) -> bytes:
    """Join frames and add the end-of-message byte."""
    return b"".join(frames) + b"\x03"


# ---- graphics ----------------------------------------------------------------
# 16 x 128 graphic = 512 bytes = two 256-byte colour planes (red first, then
# green; amber = both planes).  In each plane: 128 bytes for rows 0-7
# then 128 bytes for rows 8-15; one byte per column, bit 0 = top row of the
# band; columns are stored right-to-left (byte 0 = rightmost column).
GFX_W, GFX_H = 128, 16


def gfx_encode(pixels, width: int = GFX_W, height: int = GFX_H) -> bytes:
    """pixels(x, y) -> 0 off, 1 plane1, 2 plane2, 3 both."""
    planes = [bytearray(width * height // 8), bytearray(width * height // 8)]
    for y in range(height):
        for x in range(width):
            v = pixels(x, y)
            i = (y // 8) * width + (width - 1 - x)
            for p in range(2):
                if v & (1 << p):
                    planes[p][i] |= 1 << (y % 8)
    return bytes(planes[0] + planes[1])


def gfx_decode(data: bytes, width: int = GFX_W, height: int = GFX_H):
    half = width * height // 8

    def px(x, y):
        i = (y // 8) * width + (width - 1 - x)
        return ((data[i] >> (y % 8)) & 1) | (((data[half + i] >> (y % 8)) & 1) << 1)
    return px


def _pil():
    try:
        from PIL import Image, ImageDraw, ImageFont
    except ImportError:
        sys.exit("graphic, scroll and banner frames need Pillow:\n"
                 "  Gentoo:  emerge dev-python/pillow media-fonts/dejavu\n"
                 "  other:   pip install pillow")
    return Image, ImageDraw, ImageFont


def gfx_from_text(text: str, font: Optional[str] = None, size: int = 15, colour: int = 1,
                  align: str = "center") -> bytes:
    """Render text into a 16x128 graphic with Pillow (pip install pillow)."""
    Image, ImageDraw, ImageFont = _pil()
    try:
        fnt = ImageFont.truetype(font, size) if font else ImageFont.truetype("DejaVuSans.ttf", size)
    except OSError:
        fnt = ImageFont.load_default()
    img = Image.new("1", (GFX_W, GFX_H), 0)
    dr = ImageDraw.Draw(img)
    l, t, r, b = dr.textbbox((0, 0), text, font=fnt)
    w = r - l
    x = {"left": 0, "right": GFX_W - w}.get(align, (GFX_W - w) // 2) - l
    y = (GFX_H - (b - t)) // 2 - t
    dr.text((x, y), text, fill=1, font=fnt)
    return gfx_encode(lambda px, py: colour if img.getpixel((px, py)) else 0)


def gfx_banner(text: str, font: Optional[str] = None, size: int = 15,
               colour: int = 1) -> List[bytes]:
    """Draw text of any length 16 pixels high and cut it into 128-pixel-wide
    graphics.  Shown one after another with scroll-left and no hold, the
    pieces form one continuous full-height scrolling line.  A blank piece is
    added at the end so the text scrolls completely off."""
    Image, ImageDraw, ImageFont = _pil()
    try:
        fnt = ImageFont.truetype(font, size) if font else ImageFont.truetype("DejaVuSans.ttf", size)
    except OSError:
        fnt = ImageFont.load_default()
    probe = ImageDraw.Draw(Image.new("1", (1, 1)))
    l, t, r, b = probe.textbbox((0, 0), text, font=fnt)
    pieces = max(1, -(-(r - l) // GFX_W))
    img = Image.new("1", (GFX_W * pieces, GFX_H), 0)
    ImageDraw.Draw(img).text((-l, (GFX_H - (b - t)) // 2 - t), text, fill=1, font=fnt)
    out = []
    for k in range(pieces):
        crop = img.crop((k * GFX_W, 0, (k + 1) * GFX_W, GFX_H))
        out.append(gfx_encode(lambda px, py, c=crop: colour if c.getpixel((px, py)) else 0))
    out.append(bytes(GFX_W * GFX_H // 4))          # blank piece
    return out


# ---- session ---------------------------------------------------------------
class V15Error(Exception):
    pass


class V15Sign:
    def __init__(self, link: Transport, timeout: float = 2.0, verbose: bool = False):
        self.link, self.timeout, self.verbose = link, timeout, verbose
        self.seq = 0

    def _read_packet(self) -> bytes:
        buf, end = b"", time.monotonic() + self.timeout
        while time.monotonic() < end:
            buf += self.link.read(0.05)
            i = buf.find(V15_HDR)
            if i > 0:
                buf = buf[i:]
            if len(buf) >= 6:
                need = 6 + (buf[3] + 1 if buf[3] else 0)
                if len(buf) >= need:
                    return buf[:need]
        raise V15Error(f"no reply from sign (got {buf.hex(' ') or 'nothing'})")

    def _xfer(self, ctrl: int, data: bytes) -> bytes:
        pkt = v15_packet(ctrl, data)
        if self.verbose:
            print("TX", pkt.hex(" "), file=sys.stderr)
        self.link.write(pkt)
        rep = self._read_packet()
        if self.verbose:
            print("RX", rep.hex(" "), file=sys.stderr)
        if sum(rep[:6]) & 0xFF:
            raise V15Error("bad header checksum in reply")
        if rep[3] and sum(rep[6:]) & 0xFF:
            raise V15Error("bad data checksum in reply")
        return rep

    def connect(self, attempts: int = 3) -> bytes:
        """Venus retries the connect packet when the sign is still rebooting."""
        for i in range(attempts):
            try:
                rep = self._xfer(V15_CONNECT, b"")
                self.seq = 0
                return rep[6:-1]
            except V15Error:
                if i == attempts - 1:
                    raise
        return b""

    def drain(self) -> None:
        """Discard anything the sign sent that nobody asked for."""
        end = time.monotonic() + 0.1
        while time.monotonic() < end:
            if self.link.read(0.05):
                end = time.monotonic() + 0.1

    def wait_ready(self, timeout: float = 60.0, settle: float = 1.0,
                   progress=None) -> float:
        """After a reset: keep sending connect until the sign answers again.
        Returns the seconds it took; raises V15Error after `timeout`."""
        start = time.monotonic()
        time.sleep(settle)
        tries = 0
        while time.monotonic() - start < timeout:
            self.drain()
            tries += 1
            try:
                self._xfer(V15_CONNECT, b"")
                self.seq = 0
                return time.monotonic() - start
            except V15Error:
                if progress:
                    progress(tries, time.monotonic() - start)
                time.sleep(0.5)
        raise V15Error(f"the sign did not answer within {timeout:.0f} s after the reset")

    def request(self, op: int, args: bytes = b"", size: int = 8, sub: int = 0) -> bytes:
        """Send DATA = op, sub, args..., zero-padded to size; return reply DATA."""
        self.seq = self.seq % 15 + 1
        data = (bytes([op, sub]) + args).ljust(size, b"\0")
        rep = self._xfer(self.seq << 4, data)
        if rep[4] != (self.seq << 4) | 1:
            raise V15Error(f"reply sequence {rep[4]:02X}, expected {(self.seq << 4) | 1:02X}")
        body = rep[6:-1]
        if not body or body[0] != op:
            raise V15Error(f"reply is for command {body[:1].hex()}, expected {op:02X}")
        return body

    # -- commands --
    def set_time(self, t: Optional[_dt.datetime] = None) -> None:
        self.request(OP_SETTIME, v15_ts_bytes(t or _dt.datetime.now()), 16)

    def status(self) -> dict:
        d = self.request(OP_STATUS)
        z = lambda b: b.split(b"\0")[0].decode("latin-1")
        return {"display": z(d[1:21]), "clock": v15_ts(d[27:33]), "timestamp2": v15_ts(d[33:39]),
                "running_count": d[43], "running": z(d[44:61]), "schedule": z(d[62:82]),
                "brightness": ("auto" if d[41] else "manual") + f" level {d[42]} of 63",
                "raw": d.hex()}

    def list_files(self, graphics: bool = False) -> List[dict]:
        self.request(OP_SELECT_GFX if graphics else OP_SELECT_MSG)
        d = self.request(OP_LIST, b"\x01")
        out = []
        for k in range(8):
            e = d[8 + 28 * k: 8 + 28 * (k + 1)]
            if len(e) < 28 or not e[0]:
                continue
            out.append({"name": e[:17].split(b"\0")[0].decode("latin-1"),
                        "time": v15_ts(e[17:23]) if any(e[17:23]) else "",
                        "size": int.from_bytes(e[23:27], "little")})
        return out

    def send_file(self, name: str, content: bytes, graphic: bool = False,
                  when: Optional[_dt.datetime] = None) -> None:
        blocks = max(1, -(-len(content) // V15_BLOCK))
        hdr = (v15_name(name) + v15_ts_bytes(when or _dt.datetime.now())
               + blocks.to_bytes(2, "little") + V15_BLOCK.to_bytes(2, "little")
               + len(content).to_bytes(4, "little"))
        self.request(OP_CREATE_GFX if graphic else OP_CREATE_MSG, hdr, 64)
        for i in range(blocks):
            chunk = content[i * V15_BLOCK:(i + 1) * V15_BLOCK].ljust(V15_BLOCK, b"\0")
            self.request(OP_DATA, (i + 1).to_bytes(2, "little") + bytes(4) + chunk, 255)

    def run(self, name: str) -> None:
        self.request(OP_RUN, v15_name(name), 32)

    def stop(self, name: str) -> None:
        """Stop one running message (Venus 'stop display')."""
        self.request(OP_STOP_MSG, v15_name(name), 32)

    def reset(self, clear_memory: bool = False) -> None:
        """12 00 00 = reset, 12 00 01 = reset and clear memory (erases all
        messages and graphics).  The sign then reboots and ignores the next
        connect for about 2 s."""
        self.request(OP_RESET, b"\x01" if clear_memory else b"\x00")

    def brightness(self, level: Optional[int] = None) -> None:
        """0E 00 LL = manual level 0..63 (min 00, medium 20, max 3F);
        0E 01 3F = automatic (light sensor)."""
        if level is None:
            self.request(OP_BRIGHT, b"\x3f", sub=1)
        else:
            if not 0 <= level <= 63:
                raise V15Error("brightness level must be 0..63")
            self.request(OP_BRIGHT, bytes([level]))

    def display_off(self) -> None:
        """Venus 'power off display': stops everything that is running."""
        self.request(OP_OFF)

    def diagnostics(self, on: bool) -> None:
        self.request(OP_DIAG, sub=1 if on else 0)     # 11 01 on / 11 00 off


def _v15(a) -> V15Sign:
    if getattr(a, "serial", None) and a.dtr is None:
        a.dtr = False                       # Venus clears DTR
    s = V15Sign(open_transport(a), a.ack_timeout if a.ack_timeout > 1.0 else 2.0, a.verbose)
    s.connect()
    return s


def _v15run(a, fn) -> int:
    try:
        s = _v15(a)
    except V15Error as e:
        print("error:", e, file=sys.stderr)
        return 1
    try:
        fn(s)
        return 0
    except V15Error as e:
        print("error:", e, file=sys.stderr)
        return 1
    finally:
        s.link.close()


def cmd_v15status(a) -> int:
    def go(s):
        st = s.status()
        for k in ("display", "clock", "running", "running_count", "brightness", "schedule"):
            print(f"{k:14}: {st[k]}")
        if a.raw:
            print("raw:", st["raw"])
    return _v15run(a, go)


def cmd_v15settime(a) -> int:
    when = _dt.datetime.fromisoformat(a.at) if a.at else None

    def go(s):
        s.set_time(when)
        print("clock now:", s.status()["clock"])
    if a.dry_run:
        t = when or _dt.datetime.now()
        print(v15_packet(V15_CONNECT).hex(" "))
        print(v15_packet(0x10, (bytes([OP_SETTIME, 0]) + v15_ts_bytes(t)).ljust(16, b"\0")).hex(" "))
        return 0
    return _v15run(a, go)


def cmd_v15list(a) -> int:
    def go(s):
        for kind, g in (("messages", False), ("graphics", True)):
            print(f"{kind}:")
            for f in s.list_files(g):
                print(f"   {f['name']:17}  {f['size']:6} bytes  {f['time']}")
    return _v15run(a, go)


def cmd_v15run(a) -> int:
    return _v15run(a, lambda s: (s.run(a.name), print("running:", s.status()["running"])))


def cmd_v15stop(a) -> int:
    def go(s):
        name = a.name or s.status()["running"]
        if not name:
            print("nothing is running")
            return
        s.stop(name)
        print("stopped:", name)
    return _v15run(a, go)


def cmd_v15reset(a) -> int:
    if a.clear_memory and not a.yes:
        print("reset --clear-memory erases ALL messages and graphics on the sign.\n"
              "Run again with --yes to confirm.")
        return 1

    def go(s):
        s.reset(a.clear_memory)
        print("reset sent" + (" (memory cleared)" if a.clear_memory else ""), flush=True)
        if a.no_wait:
            print("not waiting; the sign answers again after a few seconds")
            return
        print(f"waiting for the sign to restart (up to {a.timeout:.0f} s) ...", flush=True)
        took = s.wait_ready(a.timeout, progress=(lambda n, t: print(f"  no answer yet ({t:.0f} s)",
                                                                    flush=True)) if a.verbose else None)
        st = s.status()
        print(f"sign ready after {took:.1f} s")
        print(f"clock: {st['clock']}   running: {st['running'] or '(nothing)'}")
    return _v15run(a, go)


def cmd_v15brightness(a) -> int:
    levels = {"min": 0, "minimum": 0, "medium": 32, "max": 63, "maximum": 63}
    lv = a.level.lower()
    level = None if lv == "auto" else levels.get(lv)
    if level is None and lv != "auto":
        level = int(lv, 0)

    def go(s):
        s.brightness(level)
        print("brightness:", s.status()["brightness"])
    return _v15run(a, go)


def cmd_v15off(a) -> int:
    return _v15run(a, lambda s: (s.display_off(), print("display off")))


def cmd_v15diag(a) -> int:
    return _v15run(a, lambda s: s.diagnostics(a.state == "on"))


def _gfx_colour(name, frame_no: int) -> int:
    """Graphic frames are drawn in colour planes: red 1, green 2, amber 3."""
    planes = {"red": 1, "green": 2, "amber": 3, "1": 1, "2": 2, "3": 3}
    key = str(name).lower()
    if key not in planes:
        sys.exit(f"frame {frame_no}: graphic colour must be red, green or amber, not {name!r}")
    return planes[key]


def cmd_v15message(a) -> int:
    """Build a message (graphic frames and/or text frames), upload, run.
    --frame KIND[@SECONDS]:BODY   KIND = text | graphic | scroll"""
    frames, graphics = [], []
    defaults = {"speed": a.speed, "justify": a.justify, "colour": a.colour_code}
    for i, spec in enumerate(a.frame, 1):
        head, sep, body = spec.partition(":")
        if not sep:
            sys.exit(f"frame needs KIND:BODY -> {spec!r}")
        head, _, optspec = head.partition("/")
        kind, _, secs = head.partition("@")
        hold = float(secs) if secs else a.hold
        try:
            o = parse_opts(optspec, defaults)
        except ValueError as e:
            sys.exit(f"frame {i}: {e}")
        own = {}
        if kind in ("banner", "graphic", "scroll"):
            # options may be given as KIND/opts:TEXT or as KIND:[opts]TEXT (like text lines)
            try:
                own = parse_opts(optspec)
                m = re.match(r"\[([^\]]*)\]", body)
                if m:
                    own = parse_opts(m.group(1), own)
                    body = body[m.end():]
            except ValueError as e:
                sys.exit(f"frame {i}: {e}")
        gcolour = _gfx_colour(own["colour"], i) if "colour" in own else a.colour
        if kind == "banner":
            direction = own.get("effect", "scroll-left")
            if direction not in ("scroll-left", "scroll-right"):
                sys.exit(f"frame {i}: a banner scrolls left or right, not {direction!r}")
            pieces = gfx_banner(body, a.font, a.font_size, gcolour)
            if direction == "scroll-right":       # the end of the text enters first
                pieces = pieces[-2::-1] + pieces[-1:]
            for k, bmp in enumerate(pieces):
                gname = gfx_file_name(a.graphic_prefix, len(graphics) + 1, bmp)
                graphics.append((gname, bmp))
                last = k == len(pieces) - 1
                frames.append(script_graphic_frame(gname, hold if last else 0, effect=direction))
        elif kind in ("graphic", "scroll"):
            eff = own.get("effect", "scroll-left" if kind == "scroll" else "none")
            bmp = gfx_from_text(body, a.font, a.font_size, gcolour,
                                "center" if _effect_code(eff, GFX_EFFECTS) == 0 else "left")
            gname = gfx_file_name(a.graphic_prefix, len(graphics) + 1, bmp)
            graphics.append((gname, bmp))
            frames.append(script_graphic_frame(gname, hold, effect=eff))
        elif kind == "text":
            frames.append(script_text_frame(body.split("|"), hold, a.height, o["speed"],
                                            o["justify"], o["colour"], o.get("effect", 1),
                                            o.get("font")))
        else:
            sys.exit(f"frame kind must be text, graphic, scroll or banner -> {spec!r}")
    script = script_message(frames)
    print(f"message {a.name}: {len(script)} bytes, {len(frames)} frame(s), {len(graphics)} graphic(s)")
    print("script:", printable(script))
    if a.preview:
        for gname, g in graphics:
            px = gfx_decode(g)
            print(f"{gname}:")
            for y in range(GFX_H):
                print("   " + "".join("#" if px(x, y) else "." for x in range(GFX_W)))
    if a.dry_run:
        return 0

    def go(s):
        # Same order as Venus: set the clock (time/date fields need a valid
        # clock), select + list the graphics folder, upload, run, status.
        if not a.no_settime:
            s.set_time()
        s.list_files(graphics=True)
        s.send_file(a.name, script)
        for gname, g in graphics:
            s.send_file(gname, g, graphic=True)
        if not a.no_run:
            s.run(a.name)
        st = s.status()
        print("sign running:", st["running"] or "(nothing)")
        print("sign clock  :", st["clock"])
    return _v15run(a, go)


def cmd_v15upload(a) -> int:
    """Upload message/graphic files byte for byte."""
    files = []
    for spec, gfx in [(m, False) for m in a.message or []] + [(g, True) for g in a.graphic or []]:
        name, _, path = spec.partition("=")
        files.append((name, open(path, "rb").read(), gfx))
    for name, data, gfx in files:
        print(f"{'graphic' if gfx else 'message'} {name}: {len(data)} bytes from file")

    def go(s):
        s.set_time()
        s.list_files(graphics=True)
        for name, data, gfx in files:
            s.send_file(name, data, graphic=gfx)
        if a.run:
            s.run(a.run)
        st = s.status()
        print("sign running:", st["running"] or "(nothing)")
    return _v15run(a, go)






def _txt(vals, a, b) -> str:
    s = "".join("." if v is None else (chr(v) if 32 <= v < 127 else ".") for v in vals[a:b])
    return s.split(".....")[0].rstrip(".")


def v15_describe(p: dict) -> str:
    v = p["data"]
    if p["dir"] == "open":
        return "---- port opened (new Venus session) ----"
    if not v:
        return f"{p['dir']}   no reply (timeout - sign restarting?)"
    if v[0] != V15_SYNC:
        return f"{p['dir']} {p['len']}B  (no 0x55 sync)"
    L = p["len"]
    n = L - 7 if L > 6 else 0
    ctrl = v[4]
    seq = p.get("seq", "?") if ctrl is None else ("C" if ctrl == V15_CONNECT else ctrl >> 4)
    hdr = f"{p['dir']} {L:3d}B seq={seq} N={n}"
    d = v[6:6 + n]
    if n == 0:
        return f"{hdr}  CONNECT"
    op = d[0]
    name = OP_NAMES.get(op, f"command 0x{op:02X}" if op is not None else "command ?")
    if p["dir"] == "sign>pc":
        if n == 128:
            return (f"{hdr}  STATUS REPLY  type='{_txt(d, 1, 21)}' clock={v15_ts(d[27:33])} "
                    f"running='{_txt(d, 44, 61)}' sched='{_txt(d, 62, 82)}'")
        if n == 232:
            ents = []
            for k in range(8):
                e = d[8 + 28 * k: 8 + 28 * (k + 1)]
                nm = _txt(e, 0, 17)
                if nm:
                    sz = None if None in e[23:27] else int.from_bytes(bytes(e[23:27]), "little")
                    ents.append(f"'{nm}' {v15_ts(e[17:23])} size={sz}")
            return f"{hdr}  FILE LIST  " + ("; ".join(ents) or "(empty)")
        if n == 2:
            return f"{hdr}  CONNECT REPLY"
        return f"{hdr}  reply to {name}"
    extra = ""
    if op == OP_SETTIME:
        extra = v15_ts(d[2:8])
    elif op in (OP_CREATE_MSG, OP_CREATE_GFX):
        sz = None if None in d[29:33] else int.from_bytes(bytes(d[29:33]), "little")
        extra = f"'{_txt(d, 2, 19)}' {v15_ts(d[19:25])} blocks={d[25]} size={sz}"
    elif op == OP_DATA:
        extra = f"block {d[2]}  {_txt(d, 8, 255)[:48]!r}"
    elif op in (OP_RUN, OP_STOP_MSG):
        extra = f"'{_txt(d, 2, 19)}'"
    elif op == OP_DIAG:
        extra = {0: "off", 1: "on"}.get(d[1], str(d[1]))
    elif op == OP_LIST:
        extra = f"page {d[2]}"
    elif op == OP_RESET:
        extra = "with CLEAR MEMORY" if d[2] else ""
    elif op == OP_BRIGHT:
        extra = "auto" if d[1] else f"level {d[2]} of 63"
    return f"{hdr}  {name}  {extra}".rstrip()











# --------------------------------------------------------------------------
# CLI
# --------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        description="Control a Daktronics Galaxy AE-3010 LED sign from Linux.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""examples:
  %(prog)s --serial /dev/ttyUSB0 v15status
  %(prog)s --serial /dev/ttyUSB0 v15settime
  %(prog)s --serial /dev/ttyUSB0 v15message --frame 'text:Hello|World'
  %(prog)s --serial /dev/ttyUSB0 v15message --frame 'banner:[scroll-right,amber]Long text'
  %(prog)s --serial /dev/ttyUSB0 v15reset
  %(prog)s simulate --port 3001       (then: %(prog)s --tcp 127.0.0.1:3001 v15status)
""")
    link = p.add_argument_group("link to the sign")
    link.add_argument("--serial", metavar="DEV", help="serial device, e.g. /dev/ttyUSB0 or /dev/ttyS0")
    link.add_argument("--baud", type=int, default=DEFAULT_BAUD, help="default 19200")
    link.add_argument("--parity", default="N", choices="NEO")
    link.add_argument("--bytesize", type=int, default=8, choices=(7, 8))
    link.add_argument("--stopbits", type=int, default=1, choices=(1, 2))
    link.add_argument("--rtscts", action="store_true", help="hardware flow control")
    link.add_argument("--rts", type=lambda s: s == "1", default=None, metavar="0|1",
                      help="force RTS line level")
    link.add_argument("--dtr", type=lambda s: s == "1", default=None, metavar="0|1",
                      help="force DTR line level")
    link.add_argument("--tcp", metavar="HOST[:PORT]", help="serial server / Ethernet controller (default port 3001)")
    link.add_argument("--udp", metavar="HOST[:PORT]", help="UDP RTD port (M2/M3 controllers; default 3002)")
    proto = p.add_argument_group("protocol")
    proto.add_argument("--header", default=DEFAULT_HEADER, help="8-char frame header (default 20000000)")
    proto.add_argument("--ack-timeout", type=float, default=1.0)
    proto.add_argument("--retries", type=int, default=2)
    proto.add_argument("-v", "--verbose", action="store_true", help="print every TX/RX frame")

    sub = p.add_subparsers(dest="cmd", required=True)

    def ack_opt(sp):
        sp.add_argument("--no-ack", action="store_true", help="do not wait for an acknowledgement")

    s = sub.add_parser("text", help="write text into an RTD field")
    g = s.add_mutually_exclusive_group()
    g.add_argument("--offset", type=int, default=0, help="0-based RTD offset (default 0)")
    g.add_argument("--item", type=int, help="1-based Venus 'Item Number' (offset = item-1)")
    s.add_argument("--length", type=int, help="field length: pad/truncate to this many chars")
    s.add_argument("--table", default=RTD_TEXT_TABLE, help="4-digit table code (default 4010)")
    s.add_argument("--chunk", type=int, default=0, help="split into frames of N chars")
    s.add_argument("text")
    ack_opt(s)
    s.set_defaults(func=cmd_text)

    s = sub.add_parser("clock", help="feed the Linux time/date into RTD fields")
    s.add_argument("--time-offset", type=int, default=0)
    s.add_argument("--time-length", type=int)
    s.add_argument("--time-format", default="%I:%M:%S %p")
    s.add_argument("--strip-leading-zero", action="store_true", help="' 9:05' instead of '09:05'")
    s.add_argument("--date-offset", type=int)
    s.add_argument("--date-length", type=int)
    s.add_argument("--date-format", default="%a %b %d %Y")
    s.add_argument("--table", default=RTD_TEXT_TABLE)
    s.add_argument("--once", action="store_true", help="send once and exit (for cron)")
    s.add_argument("--force", action="store_true", help="send every second even if unchanged")
    ack_opt(s)
    s.set_defaults(func=cmd_clock)

    s = sub.add_parser("settime", help="RTD: send a set-time frame built from a control code and strftime template")
    s.add_argument("--control", required=True, help="10-digit control field of the set-time frame")
    s.add_argument("--data-format", required=True,
                   help="strftime() template for the data field, may contain \\xNN escapes")
    s.add_argument("--at", help="ISO time to send instead of now")
    s.add_argument("--utc", action="store_true")
    s.add_argument("--no-stx", action="store_true", help="frame has no <STX> data section")
    s.add_argument("--dry-run", action="store_true", help="print the frame, do not send")
    ack_opt(s)
    s.set_defaults(func=cmd_settime)

    s = sub.add_parser("raw", help="send one frame with any control/data")
    s.add_argument("--control", required=True)
    s.add_argument("--data", default="", help="data field, \\xNN escapes allowed")
    s.add_argument("--no-stx", action="store_true")
    s.add_argument("--dry-run", action="store_true")
    ack_opt(s)
    s.set_defaults(func=cmd_raw)

    s = sub.add_parser("hexsend", help="send raw hex bytes and show the reply")
    s.add_argument("hex", nargs="+", help='e.g. "16 32 30 30 ..."')
    s.add_argument("--wait", type=float, default=1.0)
    s.set_defaults(func=cmd_hexsend)

    s = sub.add_parser("simulate", help="run a fake sign on TCP for testing")
    s.add_argument("--port", type=int, default=3001)
    s.add_argument("--localhost", action="store_true")
    s.add_argument("--width", type=int, default=128)
    s.add_argument("--height", type=int, default=16)
    s.add_argument("--reset-time", type=float, default=4.0,
                   help="seconds the simulated sign stays silent after a reset (default 4)")
    s.set_defaults(func=cmd_simulate)

    s = sub.add_parser("v15status", help="get status from the sign (native protocol)")
    s.add_argument("--raw", action="store_true")
    s.set_defaults(func=cmd_v15status)

    s = sub.add_parser("v15settime", help="set the sign's clock from this computer (native protocol)")
    s.add_argument("--at", help="ISO time to send instead of now, e.g. 2026-11-01T23:30:00")
    s.add_argument("--dry-run", action="store_true", help="print the packets only")
    s.set_defaults(func=cmd_v15settime)

    s = sub.add_parser("v15upload", help="upload message/graphic files byte for byte")
    s.add_argument("--message", action="append", metavar="NAME=FILE")
    s.add_argument("--graphic", action="append", metavar="NAME=FILE")
    s.add_argument("--run", metavar="NAME", help="run this message afterwards")
    s.set_defaults(func=cmd_v15upload)

    s = sub.add_parser("v15list", help="list message and graphic files on the sign")
    s.set_defaults(func=cmd_v15list)

    s = sub.add_parser("v15run", help="run (activate) a message stored on the sign")
    s.add_argument("name", help="e.g. DEFAULT\\TEST")
    s.set_defaults(func=cmd_v15run)

    s = sub.add_parser("v15stop", help="stop a running message (command 07, Venus 'stop display')")
    s.add_argument("name", nargs="?", help="message name (default: the one running)")
    s.set_defaults(func=cmd_v15stop)

    s = sub.add_parser("v15reset", help="reset the sign controller (command 12)")
    s.add_argument("--clear-memory", action="store_true", help="also erase all messages and graphics")
    s.add_argument("--yes", action="store_true", help="confirm --clear-memory")
    s.add_argument("--no-wait", action="store_true", help="do not wait for the sign to restart")
    s.add_argument("--timeout", type=float, default=60.0,
                   help="seconds to wait for the sign to answer again (default 60)")
    s.set_defaults(func=cmd_v15reset)

    s = sub.add_parser("v15brightness", help="set brightness: min, medium, max, auto or 0-63")
    s.add_argument("level")
    s.set_defaults(func=cmd_v15brightness)

    s = sub.add_parser("v15off", help="display off / stop all (command 0F, Venus 'power off display')")
    s.set_defaults(func=cmd_v15off)

    s = sub.add_parser("v15diag", help="diagnostics on/off (command 0x11)")
    s.add_argument("state", choices=("on", "off"))
    s.set_defaults(func=cmd_v15diag)

    s = sub.add_parser("v15message", help="build, upload and run a message (native protocol)",
                       formatter_class=argparse.RawDescriptionHelpFormatter,
                       epilog="""frame syntax:  KIND[@SECONDS][/OPTIONS]:BODY
  text:LINE1|LINE2      text in the sign's font.  A line may start with
                        [OPTIONS] to override the frame options for that line.
  graphic:TEXT          TEXT rendered to a 16x128 bitmap
  scroll:TEXT           same, with effect scroll-left
  banner:TEXT           full-height (16 px) text of any length, scrolling:
                        drawn once, cut into 128-pixel pieces that follow each
                        other with no pause; @SECONDS = pause before repeating.
                        Options: scroll-left (default) or scroll-right, and
                        red / green / amber
OPTIONS (comma separated):
  text effects    none scroll-left scroll-right roll-up roll-down
                  roll-left roll-right travel  (or eNN)
  graphic effects none scroll-left scroll-right scroll-up scroll-down
                  roll-up wipe-left wipe-right  (or gNN)
  speed           super-slow slow normal fast super-fast
  colour          red green amber  (text also colour=XX, 8-bit RRRGGGBB hex;
                  graphic, scroll and banner frames: red green amber)
  justify         left center right
  font            normal wide fixed graphic  (all 7 pixels high)
inline tokens: {time} {time:A-F} {date} {date:A-C} {red} {green} {amber}
  time A 24:00:00  B 24:00  C 12:00:00  D 12:00  E 12:00:00 AM  F 12:00 AM
  date A 09/29/00  B September 29, 2000  C Sep 29, 2000
example: --frame 'text@5/roll-up,green:Hello|[scroll-left,amber]World'""")
    s.add_argument("--name", default="DEFAULT\\TEST", help="message file name, max 17 chars")
    s.add_argument("--frame", action="append", required=True, help="see frame syntax below")
    s.add_argument("--hold", type=float, default=2.0, help="default hold time in seconds (2.0)")
    s.add_argument("--height", default="008", help="line height code (default 008 = 7-pixel font, two lines)")
    s.add_argument("--speed", default="normal", help="default speed (super-slow..super-fast)")
    s.add_argument("--justify", default="center", help="default justification: left center right")
    s.add_argument("--colour-code", default="red", help="default text colour: red green amber or hex")
    s.add_argument("--graphic-prefix", default="LNXGFX",
                   help="up to 6 letters/digits; names are padded to the required 17 characters")
    s.add_argument("--font", help="TrueType font file for graphic frames")
    s.add_argument("--font-size", type=int, default=15)
    s.add_argument("--colour", type=int, default=1, choices=(1, 2, 3),
                   help="graphic colour: 1 = red, 2 = green, 3 = amber")
    s.add_argument("--preview", action="store_true", help="print the graphics as ASCII art")
    s.add_argument("--no-run", action="store_true", help="upload only")
    s.add_argument("--no-settime", action="store_true", help="do not set the sign's clock first")
    s.add_argument("--dry-run", action="store_true")
    s.set_defaults(func=cmd_v15message)

    s = sub.add_parser("checksum", help="checksum of HEADER..EOT given with \\xNN escapes")
    s.add_argument("body")
    s.set_defaults(func=cmd_checksum)
    return p


def main(argv=None) -> int:
    global NO_ACK
    a = build_parser().parse_args(argv)
    NO_ACK = getattr(a, "no_ack", False)
    try:
        return a.func(a) or 0
    except (OSError, ValueError) as e:
        print("error:", e, file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())
